ROS2 Humble colcon 매뉴얼

2025-10-22, G25DR

1. colcon 개요

이 장에서는 ROS 2의 표준 빌드 도구인 colcon의 기본적인 정의와 역할을 설명하고, 그 기저에 있는 설계 철학과 핵심 개념을 탐구한다. 또한, ROS 1의 catkin과의 비교를 통해 colcon이 ROS 2의 빌드 도구로 채택된 기술적, 철학적 배경을 심도 있게 분석한다.

1.1 colcon의 정의와 역할

colcon은 ’collective construction’의 약자로, 여러 소프트웨어 패키지의 빌드, 테스트, 사용 워크플로우를 개선하고 자동화하기 위해 설계된 명령줄 도구이다.1 colcon의 가장 핵심적인 정체성은 그것이 빌드 시스템(Build System)이 아니라 빌드 도구(Build Tool), 혹은 **빌드 오케스트레이터(Build Orchestrator)**라는 점에 있다. 이는 colcon이 직접 소스 코드를 컴파일하여 실행 파일을 만드는 것이 아니라, 각 패키지에 명시된 고유의 빌드 시스템(예: C++ 패키지를 위한 CMake, Python 패키지를 위한 setuptools)을 올바른 순서로 호출하고 관리하는 역할을 수행함을 의미한다.3

colcon의 주요 역할은 다음과 같이 요약할 수 있다.

1. 패키지 탐색: 작업 공간(workspace) 내에서 package.xml 파일을 재귀적으로 탐색하여 빌드할 패키지 목록을 식별한다.

2. 의존성 분석: 각 패키지의 package.xml 파일에 명시된 의존성 정보를 바탕으로 패키지 간의 의존성 그래프를 생성한다.

3. 빌드 순서 결정: 생성된 의존성 그래프를 위상 정렬(topological sort)하여 어떤 패키지를 먼저 빌드해야 하는지 순서를 결정한다.5

4. 빌드 시스템 호출: 결정된 순서에 따라 각 패키지의 빌드 시스템을 호출하여 빌드, 테스트, 설치 과정을 수행한다.

이러한 오케스트레이션 역할을 통해 개발자는 수십, 수백 개의 패키지로 구성된 복잡한 로봇 시스템을 단일 명령어(colcon build)로 일관성 있게 빌드하고 관리할 수 있다.

1.2 설계 철학 및 핵심 개념

colcon은 ROS 1의 빌드 도구였던 catkin_make, catkin_make_isolated, catkin_tools와 ROS 2 초기 빌드 도구인 ament_tools를 사용하며 얻은 경험과 교훈을 바탕으로 설계된 결과물이다.7 그 설계 기저에는 다음과 같은 핵심 철학과 개념이 자리 잡고 있다.

• 핵심 설계 원칙: colcon은 관심사 분리(Separation of Concerns), 단일 책임 원칙(Single Responsibility Principle) 등 잘 알려진 소프트웨어 공학 원칙을 충실히 따른다.6 이로 인해 colcon 자체는 특정 빌드 시스템(예: CMake)에 대한 지식을 최소화하고, 확장 기능을 통해 다양한 빌드 시스템을 지원하는 유연하고 모듈화된 구조를 갖는다.

• 패키지 격리(Isolated Builds): catkin_make가 작업 공간의 모든 패키지를 하나의 거대한 CMake 프로젝트로 취급했던 것과 달리, colcon은 각 패키지를 완전히 격리된 환경에서 개별적으로 빌드한다. 이는 catkin_make_isolated나 catkin_tools와 유사한 접근 방식으로, 한 패키지의 빌드 과정이 다른 패키지에 예기치 않은 영향을 미치는 것을 방지하여 전체 빌드 프로세스의 안정성과 재현성을 크게 향상시킨다.6

• devel 공간의 부재: colcon의 가장 큰 특징 중 하나는 ROS 1 catkin에 존재했던 devel 공간 개념을 의도적으로 배제했다는 점이다. devel 공간은 빌드된 결과물을 소스 공간과 연결하여 빠른 개발 반복을 가능하게 했지만, 개발 환경과 실제 배포 환경 간의 불일치를 유발하는 원인이 되기도 했다. colcon은 모든 패키지가 반드시 install 단계를 거쳐 명시적인 ‘설치’ 과정을 완료하도록 강제한다. 이는 개발자가 개발 단계에서부터 배포 환경과 거의 동일한 구조에서 작업하도록 유도하며, “내 컴퓨터에서는 작동했는데 배포하니 안 된다“와 같은 고질적인 문제를 원천적으로 방지하려는 설계 의도가 담겨 있다.7

1.3 catkin과의 비교: ROS 2 빌드 도구로 채택된 배경

ROS 2는 초기 설계부터 멀티플랫폼(Linux, macOS, Windows) 지원, 실시간성 강화, 다양한 프로그래밍 언어 및 빌드 시스템과의 통합을 목표로 했다. 이러한 목표를 달성하기 위해 기존 ROS 1의 catkin 시스템은 여러 한계를 가지고 있었다.

catkin_make는 단일 CMake 컨텍스트에서 모든 패키지를 처리하여 증분 빌드 속도가 빠를 수 있었지만, 패키지 간의 숨겨진 의존성을 유발하고 CMake 기반의 catkin 패키지만을 지원하는 등 유연성이 부족했다.6 catkin_make_isolated와 catkin_tools가 이러한 문제 일부를 해결했지만, ROS 2가 요구하는 광범위한 요구사항을 모두 만족시키기에는 역부족이었다.

colcon은 이러한 배경 속에서 ROS 2의 핵심 요구사항을 충족시키기 위한 차세대 빌드 도구로 설계되었다.

• 확장성: colcon은 ROS 1의 catkin 패키지와 ROS 2의 ament 패키지를 모두 빌드할 수 있을 뿐만 아니라, package.xml 파일이 없는 순수 CMake 프로젝트나 Python setuptools 기반 프로젝트 등 다양한 종류의 패키지를 빌드할 수 있는 뛰어난 확장성을 제공한다.6

• 성능: catkin_tools와 마찬가지로 의존성이 없는 패키지들을 병렬로 빌드하여 다중 코어 CPU의 성능을 최대한 활용, 전체 빌드 시간을 단축한다.10

• 플랫폼 독립성: 특정 플랫폼이나 빌드 시스템에 종속되지 않는 모듈식 설계를 통해 Linux, macOS, Windows 등 주요 운영체제를 모두 지원한다.10

• 유지보수성: colcon은 활발하게 개발되고 있으며 여러 주체에 의해 기능이 확장되고 있어 지속 가능한 발전을 기대할 수 있다.10

이러한 기술적 우위와 설계 철학의 부합성이 colcon을 ROS 2의 공식 빌드 도구로 채택하게 된 결정적인 배경이다. colcon의 도입은 단순한 도구의 교체를 넘어, ROS 생태계의 개발 패러다임이 빠른 프로토타이핑의 편의성을 넘어 소프트웨어 공학적 안정성과 배포의 재현성을 더욱 중시하는 방향으로 진화하고 있음을 보여준다.

표 1: catkin vs. colcon 주요 차이점 비교

이 표는 두 도구의 기술적 차이를 넘어 철학적 지향점의 차이를 명확히 보여준다. 사용자는 이를 통해 colcon의 특정 기능(예: devel 공간 부재)이 ‘왜’ 그렇게 설계되었는지 근본적으로 이해하고, ROS 2의 새로운 개발 방식에 더 효과적으로 적응할 수 있다.

2. colcon 환경 설정

이 장에서는 colcon 사용을 위한 실질적인 첫 단계로, 설치 과정부터 개발 효율성을 극대화할 수 있는 다양한 편의 기능 설정 방법까지 상세하게 다룬다.

2.1 설치 및 기본 설정

colcon은 ROS 2 Humble Desktop 버전을 설치할 때 대부분 자동으로 함께 설치된다. 만약 별도로 설치해야 하거나 최신 버전으로 업데이트해야 할 경우, apt 패키지 매니저를 사용하는 것이 가장 일반적이고 권장되는 방법이다.

핵심 패키지는 python3-colcon-common-extensions이다. 이 패키지는 colcon의 코어 기능뿐만 아니라, ROS 개발에 필수적인 다양한 확장 기능(예: ROS 패키지 타입 인식, 테스트 결과 요약 등)을 포함하고 있어 ROS 개발자에게는 사실상 필수적이다.7

• 설치 명령어:

sudo apt update
sudo apt install python3-colcon-common-extensions

Python의 패키지 관리자인 pip를 통해 colcon과 그 확장 기능들을 설치하거나 업그레이드하는 것도 가능하다. 이는 시스템 패키지보다 더 최신 버전을 사용하고 싶을 때 유용할 수 있다.7

• pip를 이용한 설치/업그레이드:

python3 -m pip install -U colcon-common-extensions

일반적으로는 apt를 통한 설치로 충분하며, 특별한 이유가 없는 한 시스템 패키지 관리자를 통해 일관성을 유지하는 것이 좋다.

2.2 편의 기능 설정 (colcon_cd, 자동 완성)

colcon은 개발자의 생산성을 높이기 위한 몇 가지 유용한 편의 기능을 제공한다. 이 기능들은 기본적으로 활성화되어 있지 않으므로, 사용자가 직접 설정해야 한다.

2.2.1 colcon_cd

colcon_cd는 colcon change directory의 약자로, 작업 공간 내 특정 패키지의 소스 코드 디렉토리로 신속하게 이동할 수 있게 해주는 셸 함수이다. 수십 개의 패키지가 있는 대규모 작업 공간에서 긴 경로를 일일이 입력할 필요 없이 colcon_cd <package_name>이라는 간단한 명령만으로 원하는 패키지로 즉시 이동할 수 있어 매우 편리하다.8

• colcon_cd 설정 방법:

~/.bashrc 파일(또는 사용하는 셸의 설정 파일) 맨 아래에 다음 두 줄을 추가한다.

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/humble/" >> ~/.bashrc

첫 번째 줄은 colcon_cd 함수를 현재 셸 환경으로 불러오는 역할을 한다. 두 번째 줄은 colcon_cd가 ROS 2 시스템에 설치된 패키지들도 찾을 수 있도록 기본 검색 경로를 설정하는 것이다.8 설정 후에는 source ~/.bashrc를 실행하거나 새 터미널을 열어야 적용된다.

2.2.2 자동 완성 (Tab Completion)

자동 완성 기능은 colcon 명령어, 하위 명령어(verb), 그리고 다양한 옵션들을 탭(Tab) 키를 눌러 자동으로 완성해주는 기능이다. 이 기능은 오타를 줄여주고 긴 옵션 이름을 기억할 필요가 없게 만들어 개발 속도를 크게 향상시킨다. 이 기능을 사용하기 위해서는 colcon-argcomplete 패키지가 설치되어 있어야 한다 (일반적으로 python3-colcon-common-extensions에 포함됨).8

• 자동 완성 설정 방법:

colcon-argcomplete 패키지가 제공하는 활성화 스크립트를 셸 설정 파일에 추가한다.

echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

마찬가지로 설정 후에는 source ~/.bashrc를 실행하거나 새 터미널을 열어야 기능이 활성화된다.

이 두 가지 편의 기능을 설정하는 것만으로도 colcon을 사용하는 일상적인 개발 워크플로우가 훨씬 더 원활하고 효율적으로 변할 것이다.

3. colcon 작업 공간

colcon의 핵심 운영 단위인 작업 공간(workspace)의 물리적, 논리적 구조를 심층적으로 분석한다. 작업 공간의 기본 개념부터 colcon build 실행 후 생성되는 각 디렉토리의 역할, 그리고 여러 작업 공간을 연계하여 사용하는 언더레이와 오버레이 개념까지 상세히 다룬다.

3.1 작업 공간의 개념과 구조

ROS 2에서 작업 공간은 단순히 소스 코드를 모아두는 폴더 이상의 의미를 가진다. 이는 패키지를 개발, 빌드, 테스트, 실행하는 독립적인 환경의 단위이다. colcon 작업 공간은 특정 디렉토리 구조 규칙을 따르며, 가장 핵심적인 요소는 소스 코드를 담는 src 서브디렉토리이다.7

개발자는 먼저 작업 공간으로 사용할 루트 디렉토리(예: ~/ros2_ws)를 생성하고, 그 안에 src 디렉토리를 만든다. 모든 ROS 2 패키지의 소스 코드는 이 src 디렉토리 내에 위치해야 한다.

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

colcon 명령어는 반드시 이 작업 공간의 루트 디렉토리에서 실행되어야 한다. colcon은 실행된 위치를 기준으로 하위 디렉토리를 재귀적으로 탐색하여 빌드할 패키지를 찾기 때문이다. 만약 src 디렉토리나 다른 하위 디렉토리에서 colcon build를 실행하면, colcon은 전체 작업 공간 구조를 인식하지 못하고 일부 패키지만을 빌드하거나 아무것도 찾지 못하는 문제가 발생할 수 있다.15

colcon build 명령어를 처음 실행하면, src 디렉토리와 동일한 레벨에 build, install, log라는 세 개의 새로운 디렉토리가 생성된다. 이는 소스 코드(src)와 빌드 과정에서 생성되는 중간 산출물(build), 그리고 최종 설치 결과물(install)을 물리적으로 분리하는 ‘out-of-source’ 빌드 방식을 따른다. 이 구조는 작업 공간을 깨끗하게 유지하고, 빌드 관련 문제를 소스 코드와 분리하여 관리할 수 있게 해준다.7

3.2 핵심 디렉토리 상세 분석: src, build, install, log

colcon 작업 공간을 구성하는 네 개의 핵심 디렉토리는 각각 명확한 역할을 수행한다.

• src (Source Space):

이름 그대로 빌드하고자 하는 모든 ROS 2 패키지의 소스 코드가 위치하는 공간이다. git clone을 통해 외부 패키지를 가져오거나 ros2 pkg create 명령으로 새로운 패키지를 생성하는 작업이 모두 이 디렉토리 안에서 이루어진다. colcon은 빌드를 시작할 때 이 디렉토리 내부를 탐색하여 package.xml 파일을 가진 모든 디렉토리를 하나의 패키지로 인식한다.14

• build (Build Space):

빌드 과정에서 생성되는 모든 중간 파일들이 저장되는 공간이다. 예를 들어, C++ 코드를 컴파일할 때 생성되는 오브젝트 파일(.o), CMake가 사용하는 캐시 파일(CMakeCache.txt), 그리고 각 패키지별 빌드 설정 등이 여기에 해당된다. 각 패키지는 build 디렉토리 내에 자신만의 하위 디렉토리를 가지며, 이곳에서 격리된 빌드가 수행된다. 이 디렉토리에 저장된 중간 파일들 덕분에, 소스 코드의 일부만 변경되었을 경우 전체를 다시 컴파일하는 대신 변경된 부분만 재컴파일하는 ’증분 빌드(incremental build)’가 가능해져 빌드 시간을 단축할 수 있다.7

• install (Install Space):

모든 빌드 과정이 성공적으로 완료된 후, 최종 산출물이 설치되는 공간이다. 여기에는 실행 가능한 노드 파일, 공유 라이브러리(.so), Python 모듈, 헤더 파일, launch 파일, URDF 파일, 설정 파일 등 패키지를 실행하고 사용하는 데 필요한 모든 것이 포함된다. 각 패키지는 기본적으로 install 디렉토리 내에 자신의 이름으로 된 하위 디렉토리를 만들어 그 안에 설치된다. ROS 2 환경에서 이 작업 공간의 결과물을 사용하기 위해서는 source install/setup.bash 명령을 실행해야 한다. 이 명령은 install 디렉토리의 경로를 시스템의 PATH, LD_LIBRARY_PATH, PYTHONPATH 등의 환경 변수에 추가하여, ros2 run과 같은 명령이 이곳에 설치된 실행 파일과 라이브러리를 찾을 수 있도록 해준다.7

• log (Log Space):

colcon이 실행되는 동안 발생하는 모든 출력과 로그 정보가 저장되는 공간이다. 기본적으로 colcon build는 콘솔에 최소한의 정보만 출력하고, 상세한 빌드 과정, 경고, 오류 메시지는 모두 이 log 디렉토리 안의 파일에 기록된다. 빌드가 실패했을 때, log 디렉토리 안의 해당 패키지 로그 파일(예: stderr.log)을 확인하는 것이 원인 분석의 첫걸음이다. log 디렉토리에는 latest라는 이름의 심볼릭 링크가 있어, 가장 최근에 실행된 colcon 명령의 로그 디렉토리로 쉽게 접근할 수 있다.7

3.3 언더레이와 오버레이

ROS 2 개발은 종종 여러 개의 작업 공간을 계층적으로 쌓아 올리는 방식으로 이루어진다. 이때 사용되는 개념이 언더레이(Underlay)와 오버레이(Overlay)이다.

• 언더레이(Underlay): 현재 작업 중인 환경의 기반이 되는 ROS 환경을 의미한다. 가장 기본적인 언더레이는 ROS 2를 바이너리로 설치했을 때 생성되는 /opt/ros/humble이다. 터미널을 열고 source /opt/ros/humble/setup.bash를 실행하는 것은 이 기본 ROS 환경을 언더레이로 설정하는 행위이다.7

• 오버레이(Overlay): 기존의 언더레이 환경 위에 새롭게 빌드하는 사용자 정의 작업 공간을 의미한다. 예를 들어, ~/ros2_ws 작업 공간을 빌드하기 전에 /opt/ros/humble을 소싱했다면, ~/ros2_ws는 /opt/ros/humble의 오버레이가 된다. 이 상태에서 ~/ros2_ws/install/setup.bash를 소싱하면, ~/ros2_ws에서 빌드된 패키지들이 /opt/ros/humble의 패키지들보다 우선적으로 사용된다. 만약 오버레이에 언더레이와 동일한 이름의 패키지가 있다면, 오버레이의 패키지가 언더레이의 패키지를 ‘가리게(shadowing)’ 된다. 이는 ROS 2의 핵심 패키지를 수정하여 테스트하거나, 특정 패키지의 다른 버전을 사용하고자 할 때 매우 유용한 기능이다.7

여러 작업 공간을 연쇄적으로 소싱하여 다층적인 오버레이 구조를 만들 수도 있다. 하지만 불필요하게 많은 작업 공간을 오버레이하면 의존성 관계가 복잡해지고, 어떤 버전의 패키지가 사용되고 있는지 파악하기 어려워져 예기치 않은 문제를 유발할 수 있다. 현재 터미널 환경에 어떤 작업 공간들이 어떤 순서로 오버레이 되어 있는지는 echo $COLCON_PREFIX_PATH 명령을 통해 확인할 수 있으며, 이를 통해 환경을 명확히 인지하고 관리하는 것이 중요하다.15

colcon의 작업 공간 구조는 단순한 파일 정리를 넘어, ’상태(state)’를 가지는 개발 환경을 구성한다. build 디렉토리는 이전 빌드의 결과를 ’기억’하고, install 디렉토리는 최종 결과물을 누적하며, source된 환경은 어떤 언더레이 위에 작업이 이루어지는지를 결정한다. 이러한 ’상태’의 개념을 이해하고 관리하는 것이 colcon 관련 문제를 해결하고 효율적으로 활용하는 핵심 열쇠이다. 예를 들어, CMakeLists.txt의 중요한 변경 사항이 제대로 적용되지 않는 문제는 build 디렉토리에 남아있는 오래된 CMake 캐시, 즉 과거의 ‘상태’ 때문일 수 있다. 이 경우 rm -rf build install log 명령으로 작업 공간의 상태를 초기화하는 것이 가장 확실한 해결책이 된다.15

4. 핵심 명령어: colcon build

colcon build는 ROS 2 개발자가 가장 빈번하게 사용하는 명령어로, 작업 공간 내 패키지들을 컴파일하고 설치하는 핵심적인 역할을 수행한다. 이 장에서는 colcon build의 기본 사용법부터 특정 패키지만을 선택하여 빌드하는 방법, 그리고 개발 효율성을 극대화하는 다양한 주요 옵션들까지 상세하게 분석한다.

4.1 기본 사용법 및 전체 빌드

가장 기본적인 사용법은 작업 공간의 루트 디렉토리에서 아무런 인자 없이 colcon build를 실행하는 것이다. 이 명령은 다음과 같은 과정을 수행한다.

1. src 디렉토리와 그 하위 디렉토리를 재귀적으로 탐색하여 package.xml을 포함한 모든 패키지를 찾는다.

2. 패키지 간의 의존성을 분석하여 올바른 빌드 순서를 결정한다.

3. 시스템의 CPU 코어 수에 맞춰 가능한 한 많은 패키지를 동시에 병렬로 빌드한다.7

cd ~/ros2_ws
colcon build

이 과정은 대규모 작업 공간에서는 상당한 시간이 소요될 수 있다. 라즈베리 파이와 같이 CPU나 메모리 자원이 제한적인 시스템에서는 과도한 병렬 빌드가 시스템을 멈추게 할 수도 있다. 이러한 경우 --executor sequential 옵션을 추가하면 패키지를 한 번에 하나씩 순차적으로 빌드하여 시스템 부하를 줄일 수 있다.13

# 저사양 시스템에서 순차적으로 빌드
colcon build --executor sequential

4.2 패키지 선택 빌드

수십 개의 패키지가 포함된 대규모 작업 공간에서 단 하나의 패키지만을 수정했을 때, 전체 작업 공간을 재빌드하는 것은 매우 비효율적이다. colcon은 이러한 상황을 위해 특정 패키지만을 선택하여 빌드할 수 있는 강력한 기능들을 제공한다.

• --packages-select <pkg_name>: 명시된 이름의 패키지(들)만 정확히 빌드한다. 이 옵션은 해당 패키지가 의존하는 다른 패키지들이 이미 빌드되어 install 공간에 존재한다고 가정한다. 단일 패키지의 C++ 코드를 수정한 후 빠르게 컴파일 결과를 확인하는 데 유용하다.11

# my_package_a와 my_package_b만 빌드
colcon build --packages-select my_package_a my_package_b

• --packages-up-to <pkg_name>: 명시된 패키지와, 그 패키지가 직접 또는 간접적으로 의존하는 모든 하위 패키지들을 함께 빌드한다. 예를 들어, 패키지 A가 패키지 B에 의존하고, 패키지 B가 패키지 C에 의존할 때 --packages-up-to A를 실행하면 C, B, A 순서로 빌드된다. 이는 특정 기능을 개발하면서 관련된 여러 패키지를 함께 빌드해야 할 때 가장 일반적으로 사용되는 매우 유용한 옵션이다.11

# my_top_level_package와 그 모든 의존성 패키지를 빌드
colcon build --packages-up-to my_top_level_package

• --packages-above <pkg_name>: 명시된 패키지와, 그 패키지를 직접 또는 간접적으로 의존하는 모든 상위 패키지들을 빌드한다. 예를 들어, 여러 노드에서 공통으로 사용하는 라이브러리 패키지(예: my_library_package)를 수정했을 때, 이 라이브러리를 사용하는 모든 노드들을 다시 빌드해야 한다. 이때 이 옵션을 사용하면 매우 편리하다.22

# my_library_package를 사용하는 모든 상위 패키지들을 빌드
colcon build --packages-above my_library_package

이 외에도 정규표현식을 사용하여 패키지 이름을 패턴 매칭하는 --packages-select-regex나 특정 패키지를 빌드에서 제외하는 --packages-skip 등 다양한 고급 선택 옵션이 제공된다.25

표 2: colcon build 주요 패키지 선택 옵션

4.3 주요 빌드 옵션 상세

colcon build는 빌드 과정을 세밀하게 제어할 수 있는 다양한 옵션을 제공한다. 이 중 특히 중요하고 자주 사용되는 옵션들은 다음과 같다.

• --symlink-install: 이 옵션은 build 또는 src 공간의 파일들을 install 공간으로 복사하는 대신, 심볼릭 링크를 생성하여 연결한다. 이 방식의 가장 큰 장점은 컴파일이 필요 없는 파일(Python 스크립트, launch 파일, YAML 설정 파일, URDF 모델 파일 등)을 수정했을 때, colcon build를 다시 실행하지 않아도 변경 사항이 install 공간에 즉시 반영된다는 점이다. 이는 개발 과정의 반복 속도를 크게 향상시킨다.8 하지만 C++ 소스 코드를 수정했거나, 새로운 파일을 추가 또는 삭제하는 등 파일 구조에 변경이 있을 경우에는 반드시 colcon build를 다시 실행해야 한다. 또한, 심볼릭 링크는 소스 코드 경로에 의존하므로, 빌드된 결과물만 다른 시스템으로 옮겨 배포하는 경우에는 이 옵션을 사용해서는 안 된다.27

• --merge-install: 기본적으로 colcon은 각 패키지를 install 디렉토리 아래에 install/<package_name>과 같은 개별적인 하위 디렉토리에 설치한다(isolated install). --merge-install 옵션을 사용하면 모든 패키지의 설치 결과물을 install 디렉토리 하나에 통합하여 설치한다. 이 방식은 setup.bash 파일이 설정하는 PATH, LD_LIBRARY_PATH와 같은 환경 변수의 길이를 크게 줄여주는 효과가 있다. 특히 많은 수의 패키지를 빌드하는 Windows 환경에서는 환경 변수 길이 제한 문제에 부딪힐 수 있는데, 이때 이 옵션이 해결책이 될 수 있다.24 단점으로는 패키지 간의 파일이 섞이게 되어 격리 수준이 낮아지고, 다른 패키지의 파일을 실수로 덮어쓸 위험이 있다.

• --cmake-args: CMake를 빌드 시스템으로 사용하는 패키지(대부분의 C++ 패키지)에 추가적인 인자를 전달할 때 사용한다. 이를 통해 빌드 타입을 변경하거나 특정 컴파일러 옵션을 활성화하는 등 세밀한 제어가 가능하다.

• 디버그 빌드: colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

• 릴리즈 빌드: colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

• 테스트 비활성화: colcon build --cmake-args -DBUILD_TESTING=0.9

• --event-handlers: 빌드 과정에서 출력되는 로그의 표시 방식을 제어한다. 기본적으로 colcon은 상세 로그를 파일에만 저장하고 콘솔에는 요약 정보만 보여준다.

• console_direct+: 각 패키지의 빌드 출력을 발생하는 즉시 실시간으로 콘솔에 표시한다. 여러 패키지가 병렬로 빌드될 때 출력이 서로 섞여 보일 수 있지만, 빌드 오류가 발생한 지점을 즉시 확인할 수 있다.19

• console_cohesion+: 각 패키지의 빌드가 완료될 때까지 출력을 버퍼링했다가, 완료된 시점에 해당 패키지의 모든 출력을 한 번에 모아서 보여준다. 출력이 섞이지 않아 가독성이 높다.11

• --allow-overriding <pkg_name>: 현재 작업 공간(오버레이)에서 빌드하려는 패키지가 이미 하위 환경(언더레이, 예: /opt/ros/humble)에 존재할 경우, colcon은 잠재적인 문제를 방지하기 위해 경고를 출력한다. 이 경고를 무시하고 의도적으로 패키지를 덮어쓰고자 할 때 이 옵션을 사용한다.32

표 3: colcon build 주요 빌드 옵션

5. 테스트 자동화: colcon test

소프트웨어의 품질과 안정성을 보장하기 위해 테스트는 필수적이다. colcon은 단순히 코드를 빌드하는 것을 넘어, 작업 공간 내 패키지들의 테스트를 체계적으로 실행하고 결과를 분석하는 통합된 워크플로우를 제공한다. 이 장에서는 colcon test 명령어의 사용법과 관련 옵션들을 상세히 다룬다.

5.1 테스트 실행 및 결과 확인

colcon test 명령어는 작업 공간 내에서 테스트가 정의된 모든 패키지를 찾아 테스트를 빌드하고 실행하는 역할을 한다.

• 기본 테스트 실행: 작업 공간 루트에서 다음 명령어를 실행하면 된다.

colcon test

이 명령어는 먼저 테스트에 필요한 코드들을 빌드한 후, 각 패키지에 정의된 테스트 스위트(test suite)를 실행한다.34 한 가지 중요한 점은, colcon test를 실행하기 전에 작업 공간을 source할 필요가 없다는 것이다. colcon은 테스트가 올바른 환경 변수와 의존성을 가지고 실행될 수 있도록 내부적으로 환경을 자동으로 구성해준다.34

• 테스트 결과 확인: 테스트 실행이 완료된 후, 그 결과를 확인하기 위해서는 colcon test-result 명령어를 사용한다.

colcon test-result

기본적으로 이 명령어는 테스트가 실패했거나 오류가 발생한 패키지의 요약 정보만을 보여준다.

• 모든 결과 보기: 성공한 테스트를 포함하여 모든 패키지의 테스트 결과를 확인하고 싶다면 --all 플래그를 추가한다.

colcon test-result --all

• 상세 결과 보기: 테스트가 실패했을 때, 어떤 테스트 케이스에서 어떤 이유로 실패했는지 상세한 정보를 얻고 싶다면 --verbose 플래그를 함께 사용한다. 이는 디버깅의 첫 단계로서 매우 유용하다.34

colcon test-result --all --verbose

5.2 특정 테스트 선택 및 실행

전체 작업 공간의 모든 테스트를 실행하는 것은 시간이 많이 걸릴 수 있다. colcon은 colcon build와 마찬가지로 특정 패키지의 테스트만 선택적으로 실행하거나, 더 나아가 패키지 내의 특정 테스트 케이스만 실행할 수 있는 기능을 제공한다.

• 특정 패키지 테스트: --packages-select 옵션을 사용하여 특정 패키지의 테스트만 실행할 수 있다.

colcon test --packages-select my_package_to_test

22

• 패키지 내 특정 테스트 케이스 실행:

C++과 Python 패키지는 각각 다른 테스트 프레임워크(CTest, pytest)를 사용하므로, 특정 테스트 케이스를 선택하는 방법도 다르다.

• CTest (C++ 패키지): C++ 테스트는 주로 CTest 프레임워크를 통해 관리된다. --ctest-args 옵션을 사용하여 CTest에 직접 인자를 전달할 수 있다.22

# 'my_test_name'이라는 문자열이 포함된 테스트만 실행
colcon test --packages-select my_cpp_pkg --ctest-args -R my_test_name

# 'slow_tests'라는 문자열이 포함된 테스트는 제외하고 실행
colcon test --packages-select my_cpp_pkg --ctest-args -E slow_tests

여기서 -R은 정규표현식(Regular Expression)과 일치하는 테스트를 포함(Include)하고, -E는 제외(Exclude)하는 옵션이다.

• pytest (Python 패키지): Python 테스트는 주로 pytest 프레임워크를 사용한다. --pytest-args 옵션을 사용하여 pytest에 직접 인자를 전달할 수 있다.22

# 'test_feature_x'라는 함수 이름을 포함하는 테스트만 실행
colcon test --packages-select my_python_pkg --pytest-args -k test_feature_x

# 'integration'이라는 마커(marker)가 붙은 테스트만 실행
colcon test --packages-select my_python_pkg --pytest-args -m integration

여기서 -k는 이름 기반 필터링, -m은 마커 기반 필터링 옵션이다.

5.3 테스트 관련 주요 옵션

colcon test는 테스트 워크플로우를 더욱 효과적으로 관리하기 위한 여러 유용한 옵션을 제공한다.

• --retest-until-pass N: 실패한 테스트가 있다면, 통과할 때까지 최대 N번까지 자동으로 재시도한다. 네트워크 지연이나 미세한 타이밍 문제로 인해 간헐적으로 실패하는 테스트(flaky test)를 식별하고 안정성을 검증하는 데 유용하다.36

• --retest-until-fail N: 통과한 테스트를 실패할 때까지 최대 N번까지 자동으로 재시도한다. 이는 특정 조건에서만 드물게 발생하는 버그를 찾아내는 데 도움이 될 수 있다.36

• --return-code-on-test-failure: 테스트 스위트에서 단 하나의 테스트 케이스라도 실패하면, colcon test 명령어가 0이 아닌 종료 코드(non-zero return code)를 반환하도록 한다. 이 옵션은 Jenkins, GitHub Actions와 같은 CI/CD(지속적 통합/지속적 배포) 파이프라인에서 테스트 실패를 자동으로 감지하고 빌드를 실패 처리하는 데 필수적이다.36

• --cmake-args -DBUILD_TESTING=0: 이는 colcon test가 아닌 colcon build 명령어의 옵션이지만, 테스트 워크플로우와 밀접한 관련이 있다. 개발 과정에서 테스트를 실행할 계획이 없다면, colcon build 시 이 옵션을 추가하여 테스트 관련 코드를 아예 컴파일하지 않도록 설정할 수 있다. 이는 전체 빌드 시간을 의미 있게 단축시킬 수 있다.8

colcon의 테스트 시스템은 단순히 테스트를 실행하는 것을 넘어, 빌드-테스트-분석-디버깅으로 이어지는 통합된 품질 관리 워크플로우를 제공한다. colcon test-result는 build 디렉토리에 생성된 표준 형식의 테스트 결과 파일(예: JUnit XML)을 파싱하여 보여주는 역할을 하며 37, 이는 테스트 실행과 결과 분석이 분리될 수 있음을 의미한다. 이러한 구조는 CI 서버에서 테스트 실행 후 결과 파일을 아티팩트로 저장하고, 개발자가 나중에 이를 다운로드하여 분석하는 등의 고급 워크플로우를 가능하게 한다.

6. 고급 활용 및 모범 사례

colcon의 기본 기능을 익혔다면, 이제 생산성을 한 단계 더 끌어올리고 프로젝트를 체계적으로 관리하기 위한 고급 기법들을 활용할 차례이다. 이 장에서는 빌드 속도를 최적화하는 방법, 반복적인 작업을 자동화하는 설정, 그리고 최신 IDE와의 연동을 통해 개발 환경을 개선하는 방법을 다룬다.

6.1 빌드 최적화 및 속도 향상 기법

대규모 ROS 2 프로젝트에서는 빌드 시간이 개발 흐름을 방해하는 주요 요인이 될 수 있다. 다음 기법들을 활용하여 빌드 시간을 크게 단축할 수 있다.

• Ccache 사용:

Ccache는 ’Compiler Cache’의 약자로, 컴파일러 호출을 가로채 그 결과를 캐싱하는 도구이다. 소스 코드가 변경되지 않은 채로 다시 컴파일이 시도될 경우, Ccache는 실제 컴파일러를 실행하는 대신 캐시된 결과를 즉시 반환한다. 이는 특히 C++ 코드가 많은 대규모 작업 공간을 반복적으로 빌드할 때 극적인 속도 향상을 가져온다. ROS 개발자에게는 거의 필수적인 도구로 권장된다.15

• 설치: sudo apt install ccache

• 설정: ~/.bashrc 파일에 다음 환경 변수를 추가하여 모든 gcc/g++ 호출이 Ccache를 통하도록 설정한다.

export CC="/usr/lib/ccache/gcc"
export CXX="/usr/lib/ccache/g++"

• 확인: ccache -s 명령으로 캐시 사용 현황(히트율 등)을 확인할 수 있다.15

• 빌드 타입(Build Type)의 전략적 선택:

CMake 기반 패키지는 빌드 타입을 지정하여 최적화 수준을 조절할 수 있다.

• Release: -O3와 같은 강력한 최적화 옵션이 적용되어 실행 파일의 성능이 가장 좋다. 하지만 컴파일 시간이 길고 디버깅 정보가 포함되지 않는다. 최종 제품 배포 시 사용된다.

• Debug: 최적화가 적용되지 않으며(-O0), 디버깅 심볼(-g)이 포함된다. 컴파일 속도가 가장 빠르고 디버거를 사용한 단계별 코드 실행이 가능하다. 개발 및 디버깅 단계에서 사용된다.

• RelWithDebInfo: Release 빌드와 같이 최적화가 적용되면서도 디버깅 심볼이 포함된다. 성능과 디버깅 편의성을 모두 잡으려는 절충안이지만, 컴파일 시간이 가장 길 수 있다.

개발 중에는 주로 Debug 타입을 사용하고, 성능 테스트나 배포 시에는 Release 타입을 사용하는 등 목적에 맞게 빌드 타입을 전략적으로 선택하는 것이 중요하다.15

# 디버그 빌드
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug
# 릴리즈 빌드
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

• 병렬 작업자 수 조절:

colcon은 기본적으로 시스템의 CPU 코어 수만큼의 작업을 병렬로 수행한다. –parallel-workers 옵션을 사용하여 이 수를 명시적으로 조절할 수 있다. 예를 들어, 빌드 중 다른 작업을 원활하게 하고 싶다면 작업자 수를 줄일 수 있다.

colcon build --parallel-workers 4

6.2 defaults.yaml과 mixin을 이용한 설정 자동화

매번 colcon을 실행할 때마다 긴 옵션을 반복해서 입력하는 것은 번거롭다. colcon은 이러한 반복 작업을 줄이기 위한 두 가지 강력한 설정 자동화 메커니즘을 제공한다.

• defaults.yaml:

사용자 홈 디렉토리 아래의 .colcon 폴더에 defaults.yaml 파일을 생성하면, colcon 명령어에 대한 기본 옵션을 설정할 수 있다. 여기에 등록된 옵션은 사용자가 명시적으로 다른 값을 지정하지 않는 한 항상 적용된다.38

• 설정 파일 위치: ~/.colcon/defaults.yaml

• 예시: 개발 중 항상 --symlink-install 옵션을 사용하고, 빌드 출력을 실시간으로 보고 싶다면 다음과 같이 설정할 수 있다.

# ~/.colcon/defaults.yaml
build:
symlink-install: true
event-handlers: ["console_direct+"]

15

• mixin:

믹스인(Mixin)은 특정 목적을 위해 자주 사용되는 옵션들의 묶음을 하나의 ’별명’으로 정의하고, 필요할 때마다 –mixin <별명> 형태로 불러와 사용하는 기능이다. 예를 들어, ‘디버깅’, ‘테스트’, ‘CI용 빌드’ 등 다양한 시나리오에 맞는 옵션 셋을 미리 정의해두고 편리하게 사용할 수 있다.13

• 기본 믹스인 저장소 추가: colcon 커뮤니티에서 제공하는 유용한 믹스인 모음을 추가할 수 있다.

colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default

13

• 믹스인 사용 예시: 위 저장소를 추가하면 debug, release 등의 믹스인을 사용할 수 있다. colcon build --mixin debug 명령은 내부적으로 --cmake-args -DCMAKE_BUILD_TYPE=Debug와 같은 옵션을 자동으로 적용해준다.13

# 디버그 빌드를 위한 믹스인 사용
colcon build --mixin debug

6.3 IDE 연동을 위한 compile_commands.json 생성

CLion, Visual Studio Code와 같은 현대적인 C++ IDE는 코드 분석, 자동 완성, 리팩토링 등 강력한 기능을 제공한다. 이러한 기능이 정확하게 동작하기 위해서는 IDE가 프로젝트의 빌드 구성을 알아야 한다. compile_commands.json 파일이 바로 이 역할을 하는 표준화된 형식의 데이터베이스이다. 이 파일에는 프로젝트 내의 모든 소스 파일에 대해 어떤 컴파일러 옵션과 인클루드 경로를 사용하여 컴파일하는지에 대한 정보가 JSON 형식으로 기록되어 있다.15

colcon을 사용하여 이 파일을 쉽게 생성할 수 있다.

• 생성 방법: colcon build 시 --cmake-args를 통해 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON 옵션을 전달하면 된다.

colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

15

이 명령을 실행하면, 각 CMake 패키지의 build 디렉토리 내에 compile_commands.json 파일이 생성된다. 더 나아가 colcon-cmake 확장은 각 패키지별로 생성된 이 파일들을 하나로 통합하여, 작업 공간 루트의 build 디렉토리 최상단에 단일 compile_commands.json 파일을 추가로 생성해준다. IDE에서는 이 통합된 파일을 프로젝트의 컴파일 데이터베이스로 지정하면, 전체 작업 공간에 대해 정확한 코드 인텔리전스 기능을 활용할 수 있다.

7. 문제 해결 가이드

ROS 2 개발 과정에서 colcon을 사용하다 보면 다양한 문제에 직면하게 된다. 대부분의 문제는 몇 가지 공통된 원인에서 비롯된다. 이 장에서는 자주 발생하는 빌드 오류와 환경 문제들의 원인을 진단하고 해결하는 체계적인 방법을 제시한다.

7.1 일반적인 빌드 오류와 해결 방안

colcon build 실행 시 마주치는 대부분의 오류는 ‘의존성’, ‘캐시’, ’덮어쓰기’라는 세 가지 키워드로 요약할 수 있다.

• 의존성 누락:

• 증상: CMake Error at CMakeLists.txt:... (find_package)... Could not find a package configuration file... 또는 헤더 파일을 찾을 수 없다는 (No such file or directory) 컴파일 오류가 발생한다.

• 원인: 빌드하려는 패키지가 필요로 하는 다른 ROS 패키지나 시스템 라이브러리가 설치되지 않았거나, 설치되었더라도 현재 터미널 환경에 경로가 설정되지 않은 경우이다.

• 해결책:

1. 시스템 의존성 설치: rosdep은 package.xml을 분석하여 필요한 모든 시스템 라이브러리(예: libboost-dev)를 자동으로 설치해주는 강력한 도구이다. 작업 공간 루트에서 다음 명령을 실행하여 누락된 의존성을 모두 설치한다.20

rosdep install --from-paths src --ignore-src -r -y

2. 환경 소싱(Sourcing) 확인: 필요한 ROS 패키지가 다른 작업 공간에 빌드되어 있거나 기본 ROS 설치( /opt/ros/humble)에 포함되어 있을 수 있다. 현재 터미널에서 해당 환경의 setup.bash 파일이 source 되었는지 확인한다. 가장 좋은 방법은 새 터미널을 열고 필요한 환경을 순서대로 다시 source하는 것이다.20

• 캐시 문제:

• 증상: 소스 코드나 CMakeLists.txt를 분명히 수정했는데도 변경 사항이 빌드에 반영되지 않거나, 이전에 발생하지 않던 비논리적인 링크 오류가 발생하는 등 예측 불가능한 동작을 보인다.

• 원인: colcon의 build 디렉토리에 저장된 이전 빌드의 캐시 정보(CMake 설정, 중간 파일 등)가 현재 소스 코드 상태와 일치하지 않아 충돌을 일으키는 경우이다.

• 해결책: 가장 확실하고 간단한 방법은 작업 공간의 상태를 초기화하는 것이다. 작업 공간 루트에서 build, install, log 디렉토리를 완전히 삭제한 후, 처음부터 다시 빌드한다. 이는 많은 ‘알 수 없는’ 문제들을 해결하는 효과적인 방법이다.15

rm -rf build/ install/ log/
colcon build

• 패키지 덮어쓰기(Overriding) 경고:

• 증상: colcon build 실행 시 특정 패키지가 이미 언더레이 작업 공간에 존재한다는 경고 메시지가 출력되며 빌드가 진행되지 않을 수 있다.

• 원인: 현재 빌드하려는 오버레이 작업 공간의 패키지 이름이, 이미 source된 언더레이(예: /opt/ros/humble)에 있는 패키지 이름과 동일하기 때문이다. colcon은 의도치 않은 덮어쓰기로 인한 잠재적 문제를 방지하기 위해 기본적으로 이를 경고한다.

• 해결책: 만약 ROS 2 핵심 패키지를 수정하는 등 의도적으로 덮어쓰려는 것이 맞다면, --allow-overriding 옵션을 사용하여 빌드를 강제할 수 있다.33

colcon build --allow-overriding <package_name_to_override>

7.2 환경 및 기타 문제 해결

빌드 자체의 오류 외에도, colcon의 동작 방식이나 환경 설정 미숙으로 인해 발생하는 문제들도 있다.

• colcon이 패키지를 찾지 못할 때:

• 원인 1: colcon 명령어를 작업 공간 루트가 아닌 다른 디렉토리(예: src 내부)에서 실행했다. colcon은 현재 디렉토리 하위만 탐색한다.15

• 원인 2: 해당 패키지 디렉토리 안에 COLCON_IGNORE라는 이름의 빈 파일이 있다. 이 파일은 colcon에게 해당 디렉토리를 무시하라고 지시하는 역할을 한다.8

• 해결책: 항상 작업 공간 루트 디렉토리에서 colcon을 실행하고, COLCON_IGNORE 파일이 불필요하게 존재하는지 확인한다.

• Python 스크립트 변경이 적용되지 않을 때:

• 원인: --symlink-install 옵션 없이 빌드한 경우, src 디렉토리의 Python 파일을 수정해도 install 디렉토리에 복사된 파일은 변경되지 않는다. 따라서 ros2 run으로 실행되는 것은 수정 전의 코드이다.

• 해결책: 개발 중에는 가급적 colcon build --symlink-install을 사용한다. 만약 이미 일반 빌드를 했다면, Python 파일을 수정한 후 다시 colcon build를 실행하여 변경 사항을 install 디렉토리에 반영해야 한다.20

• 환경 변수 충돌:

• 원인: 하나의 터미널에서 여러 ROS 배포판(예: Foxy와 Humble)이나 여러 작업 공간의 setup.bash를 순서 없이 source하면 ROS_DISTRO, AMENT_PREFIX_PATH와 같은 핵심 환경 변수들이 덮어씌워져 시스템이 혼란 상태에 빠진다.

• 해결책: 문제 해결의 가장 좋은 시작은 깨끗한 새 터미널을 여는 것이다. 그리고 필요한 환경(예: /opt/ros/humble -> ~/ros2_ws1 -> ~/ros2_ws2)을 올바른 순서대로 source한다. printenv | grep ROS 또는 env | grep -i ros 명령을 통해 현재 설정된 ROS 관련 환경 변수들을 확인하여 의도한 대로 설정되었는지 점검하는 습관을 들이는 것이 매우 중요하다.20

colcon 관련 문제의 약 80%는 ‘의존성’, ‘캐시(상태)’, ’환경(source)’이라는 세 가지 키워드로 귀결된다. 문제 발생 시, 복잡한 코드 디버깅에 앞서 이 세 가지를 먼저 체계적으로 점검하는 접근법은 대부분의 문제를 효율적으로 진단하고 해결하는 데 큰 도움이 될 것이다.

8. 부록: catkin에서 마이그레이션

ROS 1에서 ROS 2로 프로젝트를 이전하는 개발자들에게 가장 큰 장벽 중 하나는 빌드 시스템의 변화이다. 이 부록은 catkin 기반의 ROS 1 패키지를 colcon과 ament_cmake를 사용하는 ROS 2 패키지로 변환하는 과정에서 필요한 핵심적인 수정 사항들을 package.xml과 CMakeLists.txt 파일을 중심으로 상세히 안내한다.

8.1 package.xml 변경 사항

package.xml 파일은 패키지의 메타 정보를 담고 있으며, ROS 2의 빌드 시스템이 패키지를 올바르게 인식하고 처리하기 위해 몇 가지 중요한 변경이 필요하다.

1. 포맷 버전 명시: ROS 2는 패키지 포맷 2 이상을 요구한다. 따라서 <package> 태그에 format="2" 또는 format="3" 속성을 반드시 추가해야 한다.45

<package>

<package format="3">

2. 빌드 타입 명시: ament 시스템은 패키지가 어떤 빌드 타입을 사용하는지 알아야 한다. <export> 태그 안에 빌드 타입을 명시적으로 선언해야 한다. C++ 패키지는 ament_cmake, Python 패키지는 ament_python을 사용한다.45

<export>
<build_type>ament_cmake</build_type>
</export>

3. 의존성 태그 변경:

• 빌드 도구 의존성: catkin 대신 ament_cmake를 빌드 도구로 지정한다.

<buildtool_depend>catkin</buildtool_depend>
<buildtool_depend>ament_cmake</buildtool_depend>

• 실행 의존성: run_depend 태그는 더 이상 사용되지 않으며, exec_depend로 변경되었다.

• 통합 의존성: 빌드 시와 실행 시 모두에 필요한 의존성(예: rclcpp, std_msgs)은 <depend> 태그 하나로 통합하여 간결하게 표현할 수 있다.45

8.2 CMakeLists.txt 변경 사항

C++ 패키지의 빌드 규칙을 정의하는 CMakeLists.txt 파일은 가장 많은 변경이 필요한 부분이다.

1. CMake 최소 버전 및 C++ 표준: ROS 2는 더 높은 버전의 CMake를 요구하며, C++14 표준을 기본으로 사용한다. 파일 상단에 이를 명시해야 한다.45

cmake_minimum_required(VERSION 3.5)
#...
if(NOT CMAKE_CXX_STANDARD)
set(CMAKE_CXX_STANDARD 14)
endif()

2. find_package 방식 변경: catkin에서는 catkin 패키지를 한 번 찾으면서 COMPONENTS 인자로 모든 의존성을 나열했다. ament_cmake에서는 ament_cmake를 먼저 찾은 후, 필요한 각 의존성 패키지를 개별적으로 find_package 해야 한다.45

# ROS 1
find_package(catkin REQUIRED COMPONENTS roscpp std_msgs)

# ROS 2
find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(std_msgs REQUIRED)

3. catkin_package()를 ament_package()로 대체:

catkin_package()는 ament_package()로 대체되지만, 사용 방식에 큰 차이가 있다.

• 위치: ament_package()는 add_executable, add_library와 같은 모든 타겟 선언이 끝난 후에 호출되어야 한다.

• 인자 분리: catkin_package()에 전달되던 CATKIN_DEPENDS, INCLUDE_DIRS 등의 인자들은 ament_package()에서 직접 받지 않는다. 대신, ament_export_dependencies(), ament_export_include_directories()와 같은 별도의 ament_export_* 함수들을 사용하여 ament_package() 전에 호출해야 한다.45

4. 타겟 의존성 연결: target_link_libraries에서 ${catkin_LIBRARIES} 변수를 사용하던 방식 대신, ament_target_dependencies() 함수를 사용하여 타겟이 어떤 ROS 패키지에 의존하는지 명시적으로 선언한다. 이 함수는 라이브러리 링크뿐만 아니라 필요한 인클루드 경로와 컴파일러 정의까지 자동으로 처리해준다.45

# ROS 1
add_executable(my_node src/my_node.cpp)
target_link_libraries(my_node ${catkin_LIBRARIES})

# ROS 2
add_executable(my_node src/my_node.cpp)
ament_target_dependencies(my_node rclcpp std_msgs)

5. 설치 규칙(Install Rules) 필수화: colcon은 devel 공간이 없으므로, 생성된 모든 결과물(실행 파일, 라이브러리, launch 파일 등)을 install 디렉토리의 적절한 위치로 복사하도록 install() 명령어를 사용하여 명시적으로 지정해야 한다. 이는 ROS 1에서는 선택 사항이었지만 ROS 2에서는 필수이다.45

install(
TARGETS my_node
DESTINATION lib/${PROJECT_NAME}
)

표 4: catkin -> ament_cmake 마이그레이션 체크리스트

이 체크리스트는 마이그레이션 과정을 구체적이고 실행 가능한 단계로 분해하여 제공한다. 개발자는 자신의 코드를 보며 각 항목을 점검하고 수정함으로써 ROS 1 패키지를 ROS 2와 호환되도록 체계적으로 업데이트할 수 있다.

9. 참고 자료

1. colcon/colcon-core: Command line tool to build sets of software packages - GitHub, https://github.com/colcon/colcon-core
2. colcon - collective construction — colcon documentation, https://colcon.readthedocs.io/
3. Package building : r/ROS - Reddit, https://www.reddit.com/r/ROS/comments/187bqpu/package_building/
4. Story of ROS 2 - Reddit, https://www.reddit.com/r/ROS/comments/1kb6n4x/story_of_ros_2/
5. The ROS build system is confusing - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/111585/the-ros-build-system-is-confusing
6. A universal build tool - ROS2 Design, https://design.ros2.org/articles/build_tool.html
7. Using colcon to build packages — ROS 2 Documentation: Eloquent documentation, https://docs.ros.org/en/eloquent/Tutorials/Colcon-Tutorial.html
8. Using colcon to build packages - ROS documentation, https://docs.ros.org/en/foxy/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.html
9. Using colcon to build packages — ROS 2 Documentation, https://docs.ros.org/en/crystal/Tutorials/Colcon-Tutorial.html
10. catkin_make vs catkin_make_isolated, which is preferred? - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/91294/catkin-make-vs-catkin-make-isolated-which-is-preferred
11. Quick start — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/user/quick-start.html
12. Robotics crash course (Part 5 - Using ROS 2’s colcon to build packages) - Jeremy Pedersen, https://jeremypedersen.com/posts/2024-08-06-pt5-ros2-colcon/
13. Using colcon to build packages — ROS 2 Documentation: Humble …, https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.html
14. 2 ROS2 basic knowledge · GitBook, https://docs.elephantrobotics.com/docs/pro630-en/11-ApplicationBaseROS/11.2-ROS2/11.2.2-ROS2_Basics.html
15. Advanced usage of colcon - Autoware Documentation, https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/others/advanced-usage-of-colcon/
16. Determine a base directory of a colcon workspace - Open Robotics Discourse, https://discourse.openrobotics.org/t/determine-a-base-directory-of-a-colcon-workspace/34034
17. Advanced usage of colcon - Autoware Universe Documentation, https://autowarefoundation.github.io/autoware-documentation/pr-366/how-to-guides/advanced-usage-of-colcon/
18. What is a Workspace? — colcon documentation, https://colcon.readthedocs.io/en/released/user/what-is-a-workspace.html
19. Log Files — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/user/log-files.html
20. Troubleshooting Guide for ROS2, Gazebo, and Robotic Simulations …, https://reference-guide-cb79e5.pages.oit.duke.edu/troubleshooting/
21. Using colcon to build packages - ROS documentation, https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.html
22. How to — colcon documentation, https://colcon.readthedocs.io/en/released/user/how-to.html
23. Build only modified packages with Colcon, ROS2 - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/88206/build-only-modified-packages-with-colcon-ros2
24. How to speed up colcon build (notably slower than catkin/cmake) and or debug causes?, https://robotics.stackexchange.com/questions/105783/how-to-speed-up-colcon-build-notably-slower-than-catkin-cmake-and-or-debug-cau
25. Package selection arguments — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/reference/package-selection-arguments.html
26. About the build system — ROS 2 Documentation: Foxy documentation, https://docs.ros.org/en/foxy/Concepts/About-Build-System.html
27. ros - Downsides to colcon’s –symlink-install option in ROS2 …, https://robotics.stackexchange.com/questions/100395/downsides-to-colcons-symlink-install-option-in-ros2
28. build - Build Packages — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/reference/verb/build.html
29. ROS2 Colcon debug symbols for use with DDD - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/91241/ros2-colcon-debug-symbols-for-use-with-ddd
30. Event handler arguments — colcon documentation, https://colcon.readthedocs.io/en/released/reference/event-handler-arguments.html
31. How do I see the commands executed during a colcon build? - Stack Overflow, https://stackoverflow.com/questions/77623755/how-do-i-see-the-commands-executed-during-a-colcon-build
32. Workspace Configuration | Clearpath Robotics Documentation, https://docs.clearpathrobotics.com/docs/ros/config/workspaces/
33. Errors with Colcon while setting up - ROS Answers archive, https://answers.ros.org/question/415139/
34. Running Tests in ROS 2 from the Command Line - ROS documentation, https://docs.ros.org/en/iron/Tutorials/Intermediate/Testing/CLI.html
35. Running Tests in ROS 2 from the Command Line — ROS 2 …, https://docs.ros.org/en/humble/Tutorials/Intermediate/Testing/CLI.html
36. test - Test Packages — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/reference/verb/test.html
37. test-result - Summarize Test Results — colcon documentation - Read the Docs, https://colcon.readthedocs.io/en/released/reference/verb/test-result.html
38. Migrating ROS/ROS2 off of catkin/colcon (towards pure CMake) - Open Robotics Discourse, https://discourse.openrobotics.org/t/migrating-ros-ros2-off-of-catkin-colcon-towards-pure-cmake/12104
39. How to configure Colcon? - ros2 - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/110230/how-to-configure-colcon
40. How to configure colcon to pass CMake arguments to a specific subproject? #683 - GitHub, https://github.com/colcon/colcon-core/issues/683
41. ROS2 setup tutorial | CLion Documentation - JetBrains, https://www.jetbrains.com/help/clion/ros2-tutorial.html
42. Errors with colcon using ros2 tutorial - Robotics Stack Exchange, https://robotics.stackexchange.com/questions/107733/errors-with-colcon-using-ros2-tutorial
43. ROS2 basics in 5 days - The Construct ROS Community, https://get-help.theconstruct.ai/t/ros2-basics-in-5-days/30977
44. Is there a way to avoid running colcon build when working with languages that do not need compilation? : r/ROS - Reddit, https://www.reddit.com/r/ROS/comments/1c5nyr1/is_there_a_way_to_avoid_running_colcon_build_when/
45. Migration guide from ROS 1 — ROS 2 Documentation: Eloquent …, https://docs.ros.org/en/eloquent/Contributing/Migration-Guide.html